import Head from 'next/head';
import RootPropTable from '../../../components/prop-tables/RootPropTable';
import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
import EnableExample from '../../../examples/enable-row-selection';
import SingleExample from '../../../examples/single-row-selection';
import ManualExample from '../../../examples/manual-selection';
import CustomizeExample from '../../../examples/customize-row-selection';

<Head>
  <title>Row Selection Feature Guide - Material React Table V1 Docs</title>
  <meta
    name="description"
    content="How to add and customize row selection checkboxes in Material React Table"
  />
</Head>

## Row Selection Feature Guide

Material React Table has a built-in row selection feature and makes it easy to manage the selection state yourself. This guide demonstrates how to enable row selection and customize the selection behavior.

### Relevant Props

<RootPropTable
  onlyProps={
    new Set([
      'enableMultiRowSelection',
      'enableRowSelection',
      'enableSelectAll',
      'enableSubRowSelection',
      'getRowId',
      'muiSelectAllCheckboxProps',
      'muiSelectCheckboxProps',
      'onRowSelectionChange',
      'positionToolbarAlertBanner',
      'selectAllMode',
    ])
  }
/>

### Relevant State

<StateOptionsTable onlyProps={new Set(['rowSelection'])} />

### Enable Row Selection

Selection checkboxes can be enabled with the `enableRowSelection` prop.

```jsx
<MaterialReactTable columns={columns} data={data} enableRowSelection />
```

#### Enable Row Selection Conditionally Per Row

You can also enable row selection conditionally per row with the same `enableRowSelection` prop, but with a callback function instead of a boolean.

```jsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableRowSelection={(row) => row.original.age > 18} //disable row selection for rows with age <= 18
/>
```

### Access Row Selection State

There are two ways to access the selection state. You can either manage the selection state yourself or read it from the table instance.

#### Manage Row Selection State

The row selection state is managed internally by default, but you will more than likely want to have access to that state yourself. Here is how you can simply get access to the row selection state, specifically:

```tsx
const [rowSelection, setRowSelection] = useState({});

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    enableRowSelection
    onRowSelectionChange={setRowSelection}
    state={{ rowSelection }}
  />
);
```

#### Read Row Selection State from Table Instance

Alternatively, you can read the selection state from the `tableInstanceRef` ref as follows:

```tsx
const tableInstanceRef = useRef<MRT_TableInstance<YouDataType>>(null); //ts

const someEventHandler = () => {
  const rowSelection = tableInstanceRef.current.getState().rowSelection;
};

return (
  <MaterialReactTable
    columns={columns}
    data={data}
    enableRowSelection
    renderTopToolbarCustomActions={() => (
      <Button onClick={someEventHandler}>
        {'Do Something with Selected Rows'}
      </Button>
    )}
    tableInstanceRef={tableInstanceRef}
  />
);
```

#### Useful Row IDs

By default, the `row.id` for each row in the table is simply the index of the row in the table. You can override this and instruct Material React Table to use a more useful Row ID with the `getRowId` prop. For example, you may want something like this:

```jsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableRowSelection
  getRowId={(originalRow) => originalRow.userId}
/>
```

As rows get selected, the `rowSelection` state will look like this:

```tsx
{
  "3f25309c-8fa1-470f-811e-cdb082ab9017": true,
  "be731030-df83-419c-b3d6-9ef04e7f4a9f": true,
  ...
}
```

This can be very useful when you are trying to read your selection state and do something with your data as the row selection changes.

<EnableExample />

### Select Row on Row Click

By default, a row can only be selected by either clicking the checkbox or radio button in the `mrt-row-select` column. If you want to be able to select a row by clicking anywhere on the row, you can add your own `onClick` function to a table body row like this:

```jsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableRowSelection
  //clicking anywhere on the row will select it
  muiTableBodyRowProps={({ row }) => ({
    onClick: row.getToggleSelectedHandler(),
    sx: { cursor: 'pointer' },
  })}
/>
```

### Disable Select All

By default, if you enable selection for each row, there will also be a select all checkbox in the header of the checkbox column. It can be hidden with the `enableSelectAll` prop.

```tsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableRowSelection
  enableSelectAll={false}
/>
```

### Single Row Selection

> New in `v1.1`!

By default, the `enableMultiRowSelection` prop is set to `true`, which means that multiple rows can be selected at once with a checkbox. If you want to only allow a single row to be selected at a time, you can set this prop to `false` and a radio button will be used instead of a checkbox.

```tsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableMultiRowSelection={false} //shows radio buttons instead of checkboxes
  enableRowSelection
/>
```

<SingleExample />

### Customize Select Checkboxes or Radio Buttons

The selection checkboxes can be customized with the `muiSelectCheckboxProps` prop. Any prop that can be passed to a Mui Checkbox component can be specified here. For example, you may want to use a different color for the checkbox or use some logic to disable certain rows from being selected.

```tsx
<MaterialReactTable
  columns={columns}
  data={data}
  enableRowSelection
  muiSelectCheckboxProps={{
    color: 'secondary',
  }}
/>
```

<CustomizeExample />

### Manual Row Selection Without Checkboxes

You may have a use case where you want to be able to select rows by clicking them, but you do not want to show any checkboxes or radio buttons. You can do this by implementing a row selection feature yourself while keeping the `enableRowSelection` prop `false` so that the default selection behavior is disabled.

<ManualExample />

View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-selection-examples)**
